Knowledge Services are SwitchYard Services that leverage KIE, and thus, Drools and/or jBPM:
Given that Drools and jBPM are very tightly integrated under KIE, much of their runtime configuration can be shared by both SwitchYard's BPM component and its Rules component. Therefore, documentation on this page refers to elements that are either exactly, or structurally, identical to both the BPM and Rules components. That is to say, any configuration element you see here can be used in the same way for both BPM and Rules. Sometimes, however, the context of the element is significant, so cases like that will be identified where applicable.
For some of the configuration elements below, you might wonder why it is a shared element between both the BPM and Rules components. For example, Channels are something only applicable to Rules, right? Yes, however what if your BPM process has a node which executes business rules, and those rules reference channels? In that case, you need a way to configure channels for the rules within your process. Thus, it is documented here.
In each description below, you will see an XML section and an Annotation section. When using the SwitchYard tooling for Eclipse, the switchyard.xml will be generated for you. You can also hand-edit this file. Alternatively, you can annotate your service interfaces with annotations, and use SwitchYard’s Maven plugin to auto-generate the switchyard.xml for you, based on those annotations. If using the plugin, you will have to configure it with either and/or both the BPMSwitchYardScanner or the RulesSwitchYardScanner.
Actions are how Knowledge Services know how to map service operation invocations to their appropriate runtime counterparts. For example, when method "myOperation" is called, what should happen? Execute some business rules? Start a business process?
Using the XML below as reference, when the SwitchyYard service’s "myOperation" operation is invoked, an action of type "ACTION_TYPE" will be taken. Note that "ACTION_TYPE" is just a placeholder here. Actual ActionTypes are specific to the BPM and Rules components. Please refer to the specific documentation on those pages.
At this time, the id attribute is only applicable to the Rules component.
Please see the Mapping section below for an explanation of the globals, inputs, and outputs sections.
XML
<actions>
<action id="myId" operation="myOperation" type="ACTION_TYPE">
<globals>
<mapping/>
</globals>
<inputs>
<mapping/>
</inputs>
<outputs>
<mapping/>
</outputs>
</action>
</actions>
Annotation
The BPM and Rules components have specific action annotations that map to specific ActionTypes. Please refer to the specific documentation on those pages.
Mappings are the way to move data in or out of the action for that operation. You can specify as many mappings as you like for an action, and they get grouped as globals, inputs or outputs:
Global mappings are used to provide data that is applicable to the entire action, and is often used in classic in/out param (or data-holder/provider) fashion. An example of a global mapping is a global variable specified within a Drools Rule Language (DRL) file.
Input mappings are used to provide data that represents parameters being fed into an action. An example of an input mapping for BPM could be a process variable used while starting a business process. For Rules, it could be a fact to insert into a rules engine session.
Output mappings are used to return data out of an action. An example of an output mapping would be a BPM process variable that you want to set as the outgoing (response) message’s content.
Currently, the only supported expressionType is MVEL, which is the default, so you don’t have to specify it. The expression itself can be any MVEL expression, and variables that are available to you by default are:
exchange - The current org.switchyard.Exchange.
context - The current org.switchyard.Context.
message - The current org.switchyard.Message.
Whatever the resultant value of the expression is constitutes the data that is made available to the action. Some examples:
expression="message.content" - This is the same as message.getContent().
expression="context[‘foo’]" scope="IN" - This is the same as context.getProperty("foo", Scope.IN).getValue(), in a null-safe manner.
Specifying the scope attribute only matters if you use the context variable inside your expression. If you don’t specify a scope, the default Context access (which is done like a Map, if you picked up on that), is done with Scope.EXCHANGE for global mappings, Scope.IN for input mappings, and Scope.OUT for output mappings.
Specifying the variable attribute is often optional, but this depends on the usage. For example, if you are specifying a global variable for a rule, or a process variable to put into (or get out of) a BPM process, then it is required. However, if the result of the expression is to be used as facts for rule session insertion, than specifying a variable name isn’t applicable.
XML
<mapping expression="theExpression" expressionType="MVEL" scope="IN" variable="theVariable"/>
Annotation
@Mapping(expression="theExpression", expressionType=ExpressionType.MVEL, scope=Scope.IN, variable="theVariable")
Drools supports the notion of "Channels", which are basically "exit points" in your DRL. Here is an example:
package com.example
rule "example rule"
when
$f : Foo ( bar > 10 )
then
channels["Bar"].send( $f.getBar() );
end
XML
<channels>
<channel class="com.example.BarChannel" name="Bar"/>
</channels>
Annotation
channels={
@Channel(value=BarChannel.class, name="Bar")
}
Channels must implement org.kie.runtime.Channel.
SwitchYard provides an out-of-the-box Channel which allows you to invoke (one-way) other SwitchYard services directly and easily from your DRL. Here is an example:
XML
<channel name="HelloWorld" reference="HelloWorld" operation="greet"/>
Annotation
import org.switchyard.component.common.knowledge.channel.SwitchYardServiceChannel; // ... @Channel(value=SwitchYardServiceChannel.class, name="HelloWorld", reference="HelloWorld", operation="greet")
Attribute Reference:
value (annotation) / class (xml) = The channel implementation class. (Default is SwitchYardServiceChannel.)
name = The channel name. (default = simple name of the implementation class)
reference = The service reference qualified name.
operation = The service reference operation name.
input = The service reference operation input name.
interfaze (annotation) = The service reference interface class name.
Listeners are used to monitor specific types of events that occur during Knowledge execution. An example of this would be to audit a BPM process, and save the audit details into a database while the process progresses. Then at a later time, these details can be reported against. There are many out-of-the-box Listeners that Drools and jBPM provide, and you can write your own. The only restriction in writing your own Listener is that it must, at the minimum, implement java.util.EventListener. However, your Listener won’t actually be registered for anything unless it also implements one of the respected KIE/Drools/jBPM Listener interfaces. For example, org.drools.event.WorkingMemoryEventListener, org.drools.event.AgendaEventListener, org.kie.event.process.ProcessEventListener, or similar.
If the Listeners provide a Constructor taking a single KieRuntimeEventManager (or KnowledgeRuntimeEventManager) as a parameter, that is used and it is assumed it will do the work of registering itself with the passed-in event manager (OOTB {{WorkingMemoryLogger}}s do this). Otherwise, a no-arg constructor is assumed, and SwitchYard will do the work of registering the Listeners for each of the respected interfaces it implements.
XML
<listeners>
<listener class="org.drools.event.DebugProcessEventListener"/>
<listener class="org.kie.event.rule.DebugWorkingMemoryEventListener"/>
<listener class="com.example.MyListener"/>
</listeners>
Annotation
listeners={
@Listener(DebugProcessEventListener.class),
@Listener(DebugWorkingMemoryEventListener.class),
@Listener(MyListener.class)
}
Loggers are special types of Listeners, and are used to output the events that occur during Knowledge execution. Support for Loggers is done using a dedicated configuration element. Events can be logged to the CONSOLE or to a FILE (or THREADED_FILE). If they are directed to a file, that log can later be opened via the Drools Eclipse tooling.
XML
<loggers>
<logger interval="2000" log="myLog" type="THREADED_FILE"/>
<logger type="CONSOLE/>
</loggers>
Annotation
loggers={
@Logger(interval=2000, log="myLog", type=LoggerType.THREADED_FILE),
@Logger(type=LoggerType.CONSOLE)
}
The only configuration element more important than Actions is the Manifest, which is where you specify where the "intelligence" of the component comes from. For the BPM component, this will be, at the minimum, the location of the BPMN 2 process definition file. For the Rules component, this will most likely be the location of DRL, DSL, DSLR or XLS files. There are two ways to to configure the Manifest:
With a KIE Container. This relies upon the existence of a META-INF/kmodule.xml configuration file.
With a manually defined list of Resources.
These two options are mutually exclusive: You have to choose one or the other!
The following examples assume there is a DRL file located at classpath: com/example/MyRules.drl
META-INF/kmodule.xml
<kmodule xmlns="http://jboss.org/kie/6.0.0/kmodule">
<kbase name="com.example">
<ksession name="my-session"/>
</kbase>
</kmodule>
XML
<manifest>
<container sessionName="my-session"/>
</manifest>
Annotation
@Manifest(container=@Container(sessionName="my-session"))
In addition to the sessionName attribute, you can also specify baseName and releaseId, if desired.
Also, scanning for updates is supported only with the container option (not the resources option). To enable this, simply set scan="true" and, optionally, scanInterval=<# of milliseconds>.
XML
<manifest>
<resources>
<resource location="com/example/MyProcess.bpmn" type="BPMN2"/>
<resource location="com/example/MyRules.drl" type="DRL"/>
</resources>
</manifest>
Annotation
@Manifest(resources={
@Resource(location="com/example/MyProcess.bpmn" type="BPMN2"),
@Resource(location="com/example/MyRules.drl" type="DRL")
})
If your resources are stored in a repository like Guvnor, they can be loaded remotely. To do so, configure a ChangeSet.xml file as a resource:
<resource location="ChangeSet.xml" type="CHANGE_SET"/>
Then, inside the ChangeSet.xml file, specify the the details of accessing the remote package:
<change-set xmlns='http://drools.org/drools-5.0/change-set' xmlns:xs='http://www.w3.org/2001/XMLSchema-instance' xs:schemaLocation='http://drools.org/drools-5.0/change-set http://anonsvn.jboss.org/repos/labs/labs/jbossrules/trunk/drools-api/src/main/resources/change-set-1.0.0.xsd'>
<add>
<resource source='http://localhost:8080/drools-guvnor/org.drools.guvnor.Guvnor/package/sandbox.michele/LATEST' type='PKG' basicAuthentication="enabled" username="admin" password="admin"/>
</add>
</change-set>
Properties are the way to provide "hints" to the underlying KIE/Drools/jBPM runtime on how certain options are configured. Rather than having to expose every single KIE/Drools/jBPM option as a configurable element or attribute within SwitchYard, they can be set as open-ended properties.
Properties are an advanced topic, so setting them should be done with care. All possible property names and values will not be listed here, but as a starting point, in your IDE open up a Type Heirarchy with a root of org.kie.conf.Option. That is your full list. Here are just a couple examples:
XML
<properties>
<property name="drools.clockType" value="pseudo"/>
<property name="drools.eventProcessingMode" value="stream"/>
</properties>
Annotation
private static final String clockTypeName = org.kie.runtime.conf.ClockTypeOption.PROPERTY_NAME;
private static final String clockTypeValue = org.drools.ClockType.PSEUDO_CLOCK.value();
private static final String eventProcessingName = org.kie.conf.EventProcessingOption.PROPERTY_NAME;
private static final String eventProcessingValue = org.kie.conf.EventProcessintOption.STREAM.getMode();
properties={
@Property(name=MyClass.clockTypeName, value=MyClass.clockTypeValue),
@Property(name=MyClass.eventProcessingName, value=MyClass.eventProcessingValue)
}